[v3] feat: a fixed directory layout for the test workspace - #49

Third in the series (#46), on top of #48. Thanks for merging that one as a merge commit again — this
branch shows only its own 6 commits.

Rebased onto v3-dev at 67e78ce. No conflicts, but the rebase did turn up two things that
needed a commit of their own; they are at the end of this description. Kotlin compiles, and
tsc --noEmit is clean in the example workspace.

Specs, compiled output and whatever a server writes while it runs all used to land wherever the
build script pointed them. With more than one environment running at once, that stopped being
workable — two local environments in the same build would have shared one run/ directory.

The layout

Everything sits under testsDir (src/test/e2e by default):

src/test/e2e/
  package.json
  tsconfig.json
  tests/                your specs
  plugins/              runner plugins you wrote yourself
  dist/                 compiled output, mirroring tests/ and plugins/
  generated/            what the environments write while they run
    local/run/          the Paper server the local environment starts
  node_modules/

Three of those are disposable — node_modules, dist, generated. Delete any of them and the
next plugwrightTest recreates it.

PlugwrightLayout in plugwright-api is the whole of it: an interface over one directory, with
the names as constants. A mode reaches it through TaskRegistrationContext.layout, and gets a
chance to seed its own spec from it in the new PlugwrightMode.applyLayoutDefaults, which runs
before validation. LocalMode uses that to place its server in the environment's own generated
directory, so a build script that never mentions runDir still gets one and two environments
never collide.

local("name") for a plugin in the workspace

plugins {
    local("stand-reset")   // src/test/e2e/plugins/stand-reset.ts
}

local(file(...)) still works and still means that exact path. The named form goes into the
config as a plugwright-workspace: specifier and is resolved against dist/plugins before the
config is written, so the runner keeps seeing a plain path.

Migrating a workspace that already exists

The compile task moves stray *.spec.ts / *.spec.js into tests/, and only while there is no
tests/ directory at all — so it happens once, on the first run after the upgrade, and never
touches a workspace that already follows the layout. It reports what it moved.

The tsconfig.json is retargeted with it: include becomes tests/**/*.ts and
plugins/**/*.ts, outDir becomes ./dist. A config the JSON parser chokes on is left alone
with a message saying what to change by hand — comments are legal in a tsconfig.json, and
rewriting one that has them would drop them.

One behaviour change worth flagging

runDir no longer defaults to <project>/run. It defaults to nothing, and an unset value is
what tells the local mode to place the server under <testsDir>/generated/<environment>/run.

For a 2.x build script that never set runDir, the first run after upgrading starts a server in
a new empty directory rather than the existing run/ — a fresh world, and no plugin config
carried over. The old directory is left alone, so nothing is lost, but it is also not picked up.
One line puts it back:

environments {
    create("local", LocalMode) {
        runDir.set(layout.projectDirectory.dir("run"))
    }
}

I did not add an automatic move for this. A server directory can be large, it can be running, and
guessing which of several environments should inherit it is not something the build can do
safely.

plugwrightInit

It now writes the layout: tests/example.spec.ts, plugins/example-plugin.ts, package.json,
tsconfig.json, and a .gitignore covering node_modules, dist and generated. Each file is
written only when it is absent. An existing .gitignore gets the missing lines appended rather
than being replaced — the workspace may well have entries of its own.

The scaffolded files moved out of the Kotlin source into
plugwright-core/src/main/resources/plugwright-init, so they are real .ts and .json files an
editor can check, with nothing escaped past the Kotlin parser. The one placeholder is
@runnerVersion@, filled from the plugin's own version down to the minor — 3.0.1 scaffolds
"@drownek/plugwright": "^3.0.0". That also fixes the stale ^2.0.3 the old template hardcoded,
which would have scaffolded a 2.x runner into a 3.0 workspace.

The example plugin it writes is a runner plugin, not a Paper one — a definePlugin with a
beforeEach and a fixture, plus the declare module block that types the fixture. It is not
loaded until you say so; the task prints the plugins { local("example-plugin") } line to add.

Two fixes that ride along

ci.yml built only runner-package, so the example's two linked plugin packages went into the
run unbuilt. It now runs npm run install:packages / npm run build:packages, two new scripts in
the root package.json that cover all three.

runner-package's prepare script is gone. npm runs prepare when a package is installed from a
directory, and it packs that directory into a staging copy that never gets its dev dependencies —
so file: linking the runner failed on rimraf: not found before it could reach tsc.
prepublishOnly still builds before a publish, which is the case that mattered.

What the rebase turned up

message-buffer.spec.ts came in with your c4a89a4, at the workspace root, after this branch had
already moved the rest of the suite into tests/. The migration only runs while there is no
tests/ directory, so nothing would have picked it up and the spec would have quietly stopped
running. It is moved in its own commit.

The example's lockfile still recorded the two plugin packages at 1.0.0 with a >=2.0.0 peer
range, from before #48 moved them to 3.0.0-dev.0. Refreshed with npm install; no dependency
changed.

On the npm scope

This branch still says @drownek/plugwright everywhere, including in the init template. That is
deliberate — it matches what v3-dev publishes today, and the rename to @plugwright/runner is
in PR 6 where you said it fits. The template takes it as one string, so the rename touches one
line here.

Docs

docs/project-layout.mdx is new. configuration.mdx, quickstart.mdx, custom-modes.mdx,
plugins.mdx, environments.mdx, writing-tests.mdx and the README are updated for the layout
and for local("name").

Merging

Same request: merge commit or rebase and merge, not squash and merge — PRs 4 through 6
are stacked on this branch. I'll rebase PR 4 onto v3-dev and open it once this lands.